TITLE: Using Ami Pro 2.0 to Create Windows 3.X Help Files PRODUCT: Ami Pro 2.0 DATE: 17-Jun-1992 PROBLEM: How can documents used to generate Windows 3.X help files be created in Ami Pro? SOLUTION: NOTE: This Technical Support Note provides information on how to use certain Ami Pro functions to create documents that can be compiled into Windows 3.X help files. It does not provide instructions on how to structure a help file, how to compile a help file, or explain help file terminology. Please refer to your Windows help compiler manual for complete information on creating help files. Have a thorough understanding of creating Windows help files before using the information in this Note. Documents used to create Windows 3.X help files can be created in Ami Pro and exported to a Rich Text Format file. The rich text file is then compiled into a Windows help file using a Windows help compiler. Style sheets (HELPATM.STY is configured for use with Adobe Type Manager that is supplied with Ami Pro 2.0 and HELPTT.STY is configured for use with Windows 3.1 TrueType fonts) and several macros that automate footnote creation and other tasks are available from Lotus. The style sheets have paragraph styles created with the appropriate superscript characters for the footnotes that are used in creating Windows help file text. Other paragraph styles are included which can be used for indented paragraphs, numbered lists, bulleted lists, etc. The style sheets and macros can be obtained on a disk by mail from the Lotus Word Processing Division Customer Service Department, 404-399-5505. The files can be obtained electronically from library 2 Lotus Write and Ami Pro files on the LotusWP CompuServe forum or the Lotus WPD bulletin board, 404-395-7707. Download the file HELP20.EXE from the bulletin board or from CompuServe. HOW TO COPY THE STYLE SHEET FILES AND THE MACRO FILES 1. Access a DOS prompt. 2. Insert the floppy disk containing the help style sheets and macro files into a floppy drive. 3. Access the drive containing the disk by typing the drive letter followed by a colon. For example, if the disk is in drive A, type at the DOS prompt: A: and press ENTER. 4. At the DOS prompt type: COPY *.STY X:\PATHNAME\STYLES and press ENTER (X:\PATHNAME\STYLES should be the correct path to the directory where Ami Pro style sheets are stored. This is usually C:\AMIPRO\STYLES). 5. At the DOS prompt type: COPY *.SMM X:\PATHNAME\MACROS and press ENTER (X:\PATHNAME\MACROS should be the correct path to the directory where Ami Pro macro files are stored. This is usually C:\AMIPRO\MACROS). HOW TO CREATE HELP FILE TEXT IN AMI PRO To use one of the Ami Pro help style sheets to format text for use in creating Windows help files, follow the steps below. Note: The style sheet HELPATM.STY has the font for each paragraph style set to the Adobe Type Manager font Arial MT. Use this style sheet if you use Adobe Type Manager. The style sheet HELPTT.STY has the font for each paragraph style set to the Windows 3.1 TrueType font Arial. Use this style sheet if you use TrueType fonts. Keep in mind the following guidelines while creating help files in Ami Pro: 1. Each help topic should be on a separate page. If a help topic ends before a full page, the last paragraph of the topic should end with a hard return (press ENTER). This will ensure that RTF paragraph styles will not span page breaks. Insert a page break after the last paragraph (choose Page / Breaks / Insert page break). 2. Do not use the Text menu to assign capitalization to text. 3. If you include numbered procedural steps, apply the Numbered List paragraph style and use the macro HLPNUMBR.SMM (choose Tools / Macros / Playback). This macro inserts a number at the beginning of all paragraphs that use the Numbered List paragraph style. The macro restarts numbering with 1 after encountering a paragraph using the Heading 2 paragraph style. 4. If you include bulleted lists, apply the Bulleted List paragraph style and use the macro HLPBULET.SMM. This macro inserts a bullet at the beginning of all paragraphs that use the Bulleted List paragraph style. Note: Do not use a style with Ami Pro special effects for numbered or bulleted paragraphs. The special effects numbers and bullets in paragraph styles do not export to Rich Text Format that the Windows help compiler uses. 5. If you use the terms Mouse and Keyboard to give separate instructions for mouse and keyboard commands, the macros HLPMOUSE.SMM and HLPKEYBD.SMM can be used to insert the words Mouse: or Keyboard: at the beginning of a paragraph. 6. Use normal apostrophe and quote marks instead of typographic characters for those marks. 7. Only alphabetic and numeric characters and underlines are recognized as footnote text by the Microsoft Windows Help Compiler. 8. Ami Pro's protected text is the equivalent of Microsoft Word's hidden text. Protected text in Ami Pro translates to hidden text when exported to Rich Text Format. How to use a help style sheet The Ami Pro help style sheets provide the following styles: Context Use for Context footnotes. The macro HLPCNTXT.SMM automatically applies this style to a Context footnote. Title Use for Title footnotes. The macro HLPTITLE.SMM automatically applies this style to a Title footnote. KeyWord Use for KeyWord footnotes. The macro HLPKYWD.SMM automatically applies this style to a KeyWord footnote. Browse Use for Browse footnotes. The macro HLPBRWSE.SMM automatically applies this style to a Browse footnote. Body Text Use for topic descriptions and other general text. This style is hyphenated, has .05 paragraph spacing below, and will break within pages and columns. Heading 1 Use for help topic context string. This style is not hyphenated, contains additional .05 paragraph spacing above and below, and will keep with the next paragraph. Heading 2 Use for help topic titles. This style is not hyphenated, contains additional .05 spacing above and below, and will break within pages and columns. Numbered List Use for numbered lists. This style left aligns the first line and indents remaining lines of a paragraph. The style does not have any special effects. The number is applied by using the macro HLPNUMBR.SMM. HLPNUMBR.SMM inserts a tab after a number and a period so that the first line of text will align on a style tab at the same position as the remaining lines of the paragraph. The style is hyphenated, has additional .05 paragraph spacing below, and will break within pages and columns. Bulleted List Use for bulleted lists. This style left aligns the first line and indents remaining lines of a paragraph. The style does not have any special effects. The bullet is applied by using the macro HLPBULET.SMM. HLPBULET.SMM inserts a tab after a bullet character so that the first line of text will align on a style tab at the same position as the remaining lines of the paragraph. The style is hyphenated, has additional .05 paragraph spacing below, and will break within pages and columns. CrossRef Use for cross-references or other paragraphs that are indented and do not need additional paragraph spacing. This style is not hyphenated, has no additional paragraph spacing above or below, and will break within pages and columns. Term This style utilizes a bold font. You may want to use it for bolded terms. The style is not hyphenated or indented, has no additional paragraph spacing above or below, and will break within a page or column. Note This style utilizes an indention for all lines. Use it for cross-references or other paragraphs that are indented and need additional paragraph spacing. This style is not hyphenated, has .05 additional paragraph spacing below, and will break within pages or columns. 1. Choose File / New. 2. Select either the style sheet HELPATM.STY or HELPTT.STY from the "Style sheet for new document" list box. 3. Choose OK. 4. Type help text and create the necessary footnotes. If you want to use the help macros from Lotus to assist you in constructing the document, follow the section titled "How to use the help macros". If you want to manually create the footnotes, cross-references, and help text, follow the section titled "How to manually enter footnotes and cross- references". After the document is completed, continue with step 5 below. 5. Save the file by choosing File / Save. 6. Specify a name for the Ami Pro file in the "File name" edit box. Do not place an X in either of the check boxes for "Keep format with document" or "Ami Pro 1.2 format". This will ensure that the file will reference the help style sheet and any changes that may be made to the style sheet. 7. Choose OK. The text is now saved in an Ami Pro file that can be edited at a later time. 8. With the Ami Pro file opened, choose File / Save As. 9. Choose Rich Text Format in the "File type" list box. 10. Specify the desired name for the rich text file in the "File name" edit box. 11. Choose OK. 12. The rich text file is ready for compiling with the Windows help compiler. How to use the help macros The help macros assist you in creating context, title, keyword, and browse footnotes, create cross-references and definitions, and create various text items. The macro names and functions are as follows: HLPCNTXT.SMM Creates a Context footnote HLPTITLE.SMM Creates a Title footnote HLPKYWD.SMM Creates a KeyWord footnote HLPBRWSE.SMM Creates a Browse footnote HLPDEF.SMM Creates a definition HLPXREF.SMM Creates a cross-reference HLPBULET.SMM Inserts a bullet and a tab at the beginning of all bulleted list paragraphs. HLPNUMBR.SMM Inserts a number, a period, and a tab at the beginning of all Numbered List paragraphs. Sequential numbering starts over with number 1 when the macro encounters a paragraph using the Heading 2 paragraph style. HLPKEYBD.SMM Inserts the word Keyboard: at the beginning of the current paragraph and bolds the word. HLPMOUSE.SMM Inserts the word Mouse: at the beginning of the current paragraph and bolds the word. Keep in mind the following guidelines while using the Ami Pro help macros: 1. The help macros assume that the first line of the page contains only a return, and the title for the help topic is on the second line. You must modify the macros if you do not use this format. 2. If you will be using several types of footnotes, create them in this order: Context, Title, KeyWord, and Browse. Each help macro places a footnote reference identifier (#,$,+,K) at the location of the insertion point, and creates the desired footnote at the bottom of the page. To use the Ami Pro help macros in conjunction with the help style sheets, follow the procedure below: 1. Using either the HELPATM.STY or the HELPTT.STY style sheet, place the insertion point on line 1 of the page and apply the style Body Text. Press ENTER. This inserts a blank line which will be used to hold the footnote references. 2. On line 2 of the page apply the paragraph style Heading 1. Type the unique internal name for the help topic (context string) and press ENTER. 3. On line 3 of the page apply the paragraph style Heading 2. Type the title of a help topic and press ENTER. This help topic title displays when a user creates bookmarks and performs searches in help. 4. On line 4 apply the paragraph style Body Text. Type the paragraph of description for the help topic specified in step 3. Press ENTER after you have completed the paragraph. 5. Continue using Heading 2 and Body Text styles for subsequent help topic titles and descriptions. 6. Place the insertion point on the first line of the page. 7. Choose Tools / Macros / Playback. Note: The macro HLPCNTXT.SMM, which you will use, assumes that the insertion point is on line one of the page and the internal title (context string) for the help topic is on the second line. You will need to modify the macro if you do not use this format. 8. Specify the name HLPCNTXT.SMM in the "Macros" list box. 9. Choose OK. The macro creates a Context footnote using the context string on line 2. It copies the context string, creates a Context footnote, and pastes the context string in that footnote. It then capitalizes the footnote text, converts any spaces to underlines, and places the insertion point on the first line of the page after the # identifier for the Context footnote. 10. With the insertion point still on line one immediately after the # identifier, choose Tools / Macros / Playback. Note: The macro HLPTITLE.SMM, which you will use, assumes that the Context footnote has already been created, and that the insertion point is immediately after the Context footnote identifier (#) on the first line of the page. You will need to modify the macro if you do not use this format. 11. Specify the name HLPTITLE.SMM in the "Macros" list box. 12. Choose OK. The macro creates a Title footnote from the title for a help topic. It copies the title for the topic, creates a Title footnote, and pastes the title in that footnote. It then places the insertion point on the first line of the page after the $ identifier for the Title footnote. 13. If you want to create optional keyword footnotes (Windows Help matches the user-entered word in a search to words entered as key words in the help topic), do so only if the help topic has a Title footnote. The title of the topic appears in the search dialog box when the user searches for the keyword. Multiple help topics can use the same keyword. The format is keyword;keyword. For example, windows;commands;dialog boxes a. With the insertion point on line one immediately after the $ identifier for the Title footnote, choose Tools / Macros / Playback. Note: The macro HLPKYWD.SMM, which you will use, assumes that the Context and Title footnotes have already been created and that the insertion point is immediately after the Title footnote identifier ($) on the first line of the page. You will need to to modify the macro if you do not use this format. b. Choose the name HLPKYWD.SMM from the "Macros" list box. c. Choose OK. d. Type the keyword entries for the footnote. Press ESC after you have typed the last keyword entry. This places the insertion point at the end of line one. 14. If you use a browse sequence, enter the browse footnote last. The format is topic:nnn where topic is the sequence list name and nnn is the sequence number for the topic. For example, BASICS:010. The numbers should all have the same length. For single numbers, use two zeroes as place holders for the first two digits (001, for example), for two-digit numbers, use one zero as a place holder (010, for example). If browse sequences are numbered in increments of five or ten and use one or more zeroes as place holders, you can easily insert additional topics at a later time. Tip: If your help files contain many help topics, produce a table of contents to obtain a list of all the topics. This can be done by creating a table in a separate Ami Pro file (choose Tools / Tables). The table should contain a row for each help topic. Create a formula (choose Table / Edit formula) in column A of the table to sequentially number the topics. For example, cell A1 could have the value 5. Create the formula A1+5 in cell A2. Copy the formula in A2 to the remainder of the cells in column A to get sequential numbering in five-unit increments. Type the help topic titles in column B. Use the table as a reference when you assign the Browse sequence numbers to help topics, adding the appropriate number of zeroes as place holders. 15. Follow these steps if you want to create a cross-reference (jump term): Note: If the text you type matches the text in a Context footnote for a help topic, you can run the HLPXREF.SMM macro. If the text you type does not match a Context footnote, you will need to manually create the cross- reference following the procedure in the section titled "How to manually enter footnotes and cross-references". a. Place the insertion point where you want to create a cross-reference. b. Type the text you want the user to see as the cross-reference. This is usually the title for a help topic. c. Select (shade) the cross-reference text. Note: The text must be selected in order for the macro to play back properly. The selected text must match the text in a Context footnote for a help topic. Do not double-click on a single word to select it because this selects both the word and the space after the word. d. Choose Tools / Macros / Playback. e. Select the name HLPXREF.SMM in the "Macros" list box. f. Choose OK. HLPXREF.SMM creates a cross-reference from the selected text. It copies the selected text and pastes the text immediately after the original text. It then capitalizes the cross-reference text, converts any spaces to underlines, protects the text, double underlines the original text, and places the insertion point at the end of the line. 16. Follow these steps if you want to create a definition term. a. Place the insertion point where you want to create a term that requires definition. b. Type the term. This is usually the title for a help topic. c. Select (shade) the term. Note: The text must be selected in order for the macro to play back properly. The selected text must match the text in a Context footnote for a help topic. Do not double-click on a single word to select it because this selects both the word and the space after the word. d. Choose Tools / Macros / Playback. e. Select the name HLPDEF.SMM in the "Macros" list box. f. Choose OK. HLPDEF.SMM creates a definition term from the selected text. It copies the selected text and pastes the text immediately after the original text. It then capitalizes the definition term text, converts any spaces to underlines, protects the text, underlines the original text, and places the insertion point at the end of the line. 17. Follow these steps if you want to use the HLPMOUSE.SMM or HLPKEYBD.SMM macros. a. Place the insertion point in the paragraph that should be preceded by the word Mouse: or Keyboard:. b. Choose Tools / Macros / Playback. c. Choose the name HLPMOUSE.SMM (to insert the word Mouse:) or the name HLPKEYBD.SMM (to insert the word Keyboard:) in the "Macros" list box. d. Choose OK. The bolded word Mouse: or Keyboard: is inserted at the beginning of the paragraph. 18. Follow these steps if you want to use the HLPNUMBR.SMM macro. a. Assign the paragraph style Numbered List to all paragraphs that you want numbered. Assign a paragraph style by pressing the function key assigned to the paragraph style, selecting a paragraph style name from the paragraph styles list box, or selecting a style from the style status button on the status bar while the insertion point is in the paragraph. b. Choose Tools / Macros / Playback. c. Select the name HLPNUMBR.SMM from the "Macros" list box. d. Choose OK. The macro searches for the style Numbered List throughout the file. Each time a paragraph using that style is located, a number, period, and tab are inserted at the beginning of the paragraph. The numbers are sequential until a paragraph using the Heading 2 style is encountered. The first paragraph using the Numbered List style after a paragraph using the Heading 2 style is numbered one. Numbers continue sequentially until the next Heading 2 style is encountered, then the numbering starts again with 1. The macro assumes that each time Heading 2 is used, a new topic has been introduced and numbered list items should start over with number 1 for the new topic. 19. Follow these steps if you want to use the HLPBULET.SMM macro. a. Assign the paragraph style Bulleted List to all paragraphs that you want bulleted. Assign a paragraph style by pressing the function key assigned to the paragraph style, selecting a paragraph style name from the paragraph styles list box, or selecting a style from the style status button on the status bar while the insertion point is in the paragraph. b. Choose Tools / Macros / Playback. c. Select the name HLPBULET.SMM from the "Macros" list box. d. Choose OK. The macro searches for the style Bulleted List throughout the file. Each time a paragraph using that style is located, a bullet from the Windows Symbol font and a tab are inserted at the beginning of the paragraph. How to manually enter footnotes and cross-references 1. Creating footnotes a. Using either the HELPATM.STY or the HELPTT.STY style sheet, place the insertion point where a footnote reference identifier should appear. b. Choose Tools / Footnote / Insert Footnote. c. Choose OK. d. The insertion point will be placed near the bottom of the page. e. Type the desired footnote text. Note: If you are typing a Context footnote, you must convert any spaces between words in the Context footnote to underlines, and capitalize all text in the footnote. For example, PRINTING_A_DOCUMENT. f. Assign the appropriate paragraph style for the help topic. For example, if a browse sequence is being typed, choose the BROWSE paragraph style. Assign a paragraph style by pressing the function key assigned to the paragraph style, selecting a paragraph style name from the paragraph styles list box, or selecting a style from the style status button on the status bar while the insertion point is in the footnote text. g. After typing the footnote text, press ESCAPE to position the insertion point immediately after the footnote reference identifier. h. Repeat steps a - g until all footnotes are completed. 2. Creating cross-references a. Create cross-references by double underlining the text representing the cross-reference and marking the corresponding context string as protected text (select the text, choose Edit / Mark Text / Protected Text). Create definition terms by single underlining the text representing the definition term and marking the corresponding context string as protected text (select the text, choose Edit / Mark Text / Protected Text). Note: Ami Pro's Protected Text is the equivalent of Microsoft Word's Hidden Text. Protected Text in Ami Pro translates to Hidden Text when exported to Rich Text Format.